feat(data): record which feed a cached series came from (#696, part 1… - #710

… of 2)

Schema v17. The provenance half of #696, landing BEFORE the gate that reads it -- a gate built on a feed inferred at read time would encode the bug it exists to fix.

THE BUG. keel's liquidity statistic is median(volume * close) over cached candles, and every threshold keyed on it was calibrated against venue-reported volume. That is coherent on a crypto exchange: Coinbase's own volume IS the scale the floor was chosen against. It is not coherent on Alpaca's IEX feed, which reports one US equity exchange's own executions. The cost-fidelity run measured MSFT -- one of the most liquid securities in the world -- cached at $186M/day against a model anchored at $500M, and priced it as a thin asset. Nothing recorded which feed produced those bars, so the answer was whatever broker.data_feed happened to be loaded when someone later read the series.

WHAT LANDS HERE.

candle_series_feed, keyed on (product_id, granularity, feed) -- NOT a mutable column on candles. A series fetched under both feeds records BOTH rows, because that is what happened; a single overwritable column would let the most recent fetch erase the fact that most of the bars came from somewhere narrower, and a mixed series is exactly the case a reader most needs warning about.

NO BACKFILL, and that is the point rather than a shortcut. Seeding rows from the current broker.data_feed would manufacture precisely the claim the table exists to make checkable, for years of bars that may have come from elsewhere. An empty table means "unrecorded", which is TRUE of every pre-existing series and is a different statement from "consolidated" -- reports_consolidated_volume returns None for the first and False/True for the second, and callers must not conflate the absence of evidence with evidence.

keel/data/feed_scope.py carries the design, whose core is an ASYMMETRY: a single-venue feed's volume is a LOWER BOUND on consolidated volume, never an upper one. Volume at or above the floor on a partial feed is therefore a CONCLUSIVE pass -- if a name traded that much on one venue alone it necessarily traded at least that much in total -- while volume below the floor licenses no claim either way and must be refused as unmeasured rather than reported as thin. That is what lets this be honest without encoding any venue's market share: the bound holds for any share below 100%, so nothing here has a percentage in it that market structure could invalidate. test_the_bound_needs_no_market_share pins that no figure leaks into executable code, because the one thing that must never happen is someone scaling a volume statistic by an assumed share.

An unrecognised feed id reads as PARTIAL, which costs a conclusive pass on a consolidated feed nobody declared and never grants one on a narrow feed nobody declared.

Adapters declare their own feed (volume_feed_id), qualified by venue -- alpaca:iex / alpaca:sip, coinbase -- never bare iex, which would collide the day another venue routes there. Declaration is structural and optional: an adapter that declares nothing records nothing, so unrecorded stays unrecorded rather than every crypto series silently acquiring a provenance nobody established. Forcing all five adapters to implement it would invite a placeholder, which is the one value that must never enter this table.

Tests: 31 across three files.
tests/data/test_series_feed_provenance.py -- 16, the storage contract
tests/data/test_feed_scope.py -- 11, the scope verdict
tests/data/test_feed_provenance_is_wired.py -- 4, the fetch path actually
carries the declaration; without these the whole thing degrades silently to
pre-issue behaviour with a schema and a module suggesting otherwise

The provenance and wiring suites were written test-first. feed_scope.py was NOT -- I wrote it before its tests, which is the wrong order; the 8-mutant run below is what establishes those tests constrain the code rather than merely describe it.

Mutation-verified, 8 mutants, all killed: unrecorded reading as consolidated; any for all on a mixed series; alpaca:iex declared consolidated; a blank declaration accepted; provenance recorded for an empty batch; an empty feed string accepted; a re-fetch overwriting first_seen_ts; a missing table raising instead of reading empty.

Five existing version pins move 16 -> 17. They are literals on purpose -- a deliberate speed bump that makes a schema bump a decision someone acknowledged.

Refs #696

Claude-Session: https://claude.ai/code/session_01NzuKAe2RVrPt9acVAWjRyL

What & why

Tests-first evidence

• Tests written first, seen failing for the right reason

Gates (all must pass)

• uv run ruff check clean
• uv run mypy clean
• uv run pytest -q green

Scope check

• This PR touches a rail or a default classification — checked means it DOES;
  leave checked only if true, and if so: cite the source and open the discussion
  BEFORE review (CONTRIBUTING.md, "Governance: rulings vs. machinery").
• New dependency added (needs discussion first)